import "@site/src/languages/highlight";

# App

**描述：**

&emsp;&emsp;管理应用程序信息的单例类。

## frame

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;引擎运行到当前时间经过的帧数。

**签名：**
```tl
const frame: integer
```

## bufferSize

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;渲染主帧的缓冲纹理的大小。

**签名：**
```tl
const bufferSize: Size
```

## visualSize

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;屏幕的逻辑视觉大小。
视觉大小仅在应用程序窗口大小更改时更改。

**签名：**
```tl
const visualSize: Size
```

## devicePixelRatio

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;设备显示的像素密度比。
等于渲染缓冲纹理的像素大小除以应用程序窗口的大小。

**签名：**
```tl
const devicePixelRatio: number
```

## App.Platform

**类型：** 枚举。

**描述：**

&emsp;&emsp;游戏引擎运行的平台类型。

**签名：**
```tl
enum Platform
	"Windows"
	"Android"
	"macOS"
	"iOS"
	"Linux"
	"Unknown"
end
```

## platform

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;游戏引擎当前运行的平台。

**签名：**
```tl
const platform: Platform
```

## version

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;游戏引擎的版本字符串。
格式为“v0.0.0.0”。

**签名：**
```tl
const version: string
```

## deps

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;游戏引擎的第三方依赖库的版本信息。

**签名：**
```tl
const deps: string
```

## deltaTime

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;自从上一帧游戏更新以来间隔的时间（以秒为单位）。

**签名：**
```tl
const deltaTime: number
```

## elapsedTime

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;从当前游戏帧开始到本次API调用经过的时间（以秒为单位）。

**签名：**
```tl
const elapsedTime: number
```

## totalTime

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;游戏引擎直到上一帧结束为止，已经运行的总时间（以秒为单位）。
在同一个游戏帧中多次调用时得到的是一个常数。

**签名：**
```tl
const totalTime: number
```

## runningTime

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;直到调用该API为止，游戏引擎已经运行的总时间（以秒为单位）。
在同一个游戏帧中多次调用时得到一个递增的数字。

**签名：**
```tl
const runningTime: number
```

## rand

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;基于Mersenne Twister算法生成的随机数。
由同一种子生成的随机数在每个平台上会保持一致。

**签名：**
```tl
const rand: integer
```

## maxFPS

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;游戏引擎可以运行的最大有效帧率。
最大有效帧率是通过设备屏幕的最大刷新率推断出来的。

**签名：**
```tl
const maxFPS: integer
```

## debugging

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;游戏引擎是否运行在调试模式下。

**签名：**
```tl
const debugging: boolean
```

## testNames

**类型：** 只读成员变量。

**描述：**

&emsp;&emsp;引擎内置的C++测试的测试名称（用于辅助引擎本身开发）。

**签名：**
```tl
const testNames: {string}
```

## locale

**类型：** 成员变量。

**描述：**

&emsp;&emsp;当前系统的语言环境字符串，格式例如：`zh-Hans`，`en`.

**签名：**
```tl
locale: string
```

## themeColor

**类型：** 成员变量。

**描述：**

&emsp;&emsp;Dora SSR的主题颜色。

**签名：**
```tl
themeColor: Color
```

## seed

**类型：** 成员变量。

**描述：**

&emsp;&emsp;Dora SSR的随机数种子。

**签名：**
```tl
seed: integer
```

## targetFPS

**类型：** 成员变量。

**描述：**

&emsp;&emsp;游戏引擎应该运行的目标帧率。
仅在`fpsLimited`设置为true时有效。

**签名：**
```tl
targetFPS: integer
```

## fpsLimited

**类型：** 成员变量。

**描述：**

&emsp;&emsp;游戏引擎是否自动限制帧率。
将`fpsLimited`设置为true，会使引擎通过执行一个忙等待的死循环以获取更加精准的机器时间，并计算切换到下一帧的时间点。
这是在PC机Windows系统上的通常做法，以提升CPU占用率来提升游戏的性能。但这也会导致额外的芯片热量产生和电力消耗。

**签名：**
```tl
fpsLimited: boolean
```

## idled

**类型：** 成员变量。

**描述：**

&emsp;&emsp;游戏引擎当前是否处于闲置状态。
将`idled`设置为true，将使游戏逻辑线程使用`sleep`系统调用来等待进入下一个游戏帧的时间点。
由于操作系统定时器存在一定程度的误差，可能导致游戏引擎睡眠过头而错过几个游戏帧。
闲置状态可以减少额外的CPU占用。

**签名：**
```tl
idled: boolean
```

## fullScreen

**类型：** 成员变量。

**描述：**

&emsp;&emsp;游戏引擎是否运行在全屏模式下。
在Android和iOS平台上无法设置此属性。

**签名：**
```tl
fullScreen: boolean
```

## alwayOnTop

**类型：** 成员变量。

**描述：**

&emsp;&emsp;游戏引擎是否运行在窗口置顶模式下。
在Android和iOS平台上无法设置此属性。

**签名：**
```tl
alwayOnTop: boolean
```

## winSize

**类型：** 成员变量。

**描述：**

&emsp;&emsp;应用程序窗口大小。
由于显示设备的DPI不同，可能会与实际的可视大小有差异。
在Android和iOS平台上无法设置此属性。

**签名：**
```tl
winSize: Size
```

## winPosition

**类型：** 成员变量。

**描述：**

&emsp;&emsp;应用程序窗口位置。
在Android和iOS平台上无法设置此属性。

**签名：**
```tl
winPosition: Vec2
```

## runTest

**类型：** 函数。

**描述：**

&emsp;&emsp;运行特定的包含在引擎中的C++测试函数。

**签名：**
```tl
runTest: function(self: App, name: string): boolean
```

**参数：**

| 参数名 | 类型 | 描述 |
| --- | --- | --- |
| name | string | 要运行的测试的名称。 |

**返回值：**

| 返回类型 | 描述 |
| --- | --- |
| boolean | 测试是否成功运行。 |

## openURL

**类型：** 函数。

**描述：**

&emsp;&emsp;在系统默认的浏览器中打开指定的URL地址。

**签名：**
```tl
openURL: function(self: App, url: string)
```

**参数：**

| 参数名 | 类型 | 描述 |
| --- | --- | --- |
| url | string | 要打开的URL地址。 |

## install

**类型：** 函数。

**描述：**

&emsp;&emsp;用于自更新游戏引擎。

**签名：**
```tl
install: function(self: App, path: string)
```

**参数：**

| 参数名 | 类型 | 描述 |
| --- | --- | --- |
| path | string | 新版本引擎文件的路径。 |

## shutdown

**类型：** 函数。

**描述：**

&emsp;&emsp;关闭游戏引擎。
该函数在Android和iOS平台不会生效，以遵循移动平台上应用程序规范。

**签名：**
```tl
shutdown: function(self: App)
```